home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / standard / monitor.z / monitor
Encoding:
Text File  |  1998-10-30  |  7.3 KB  |  199 lines

  1.  
  2.  
  3.  
  4. MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))                                                        MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      monitor, moncontrol - prepare execution profile
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ccccmmmmppppllllrrrrssss////mmmmoooonnnn....hhhh>>>>
  13.  
  14.      iiiinnnntttt mmmmoooonnnniiiittttoooorrrr((((iiiinnnntttt mmmmooooddddeeee,,,, uuuunnnnssssiiiiggggnnnneeeedddd ggggrrrraaaaiiiinnnn,,,, iiiinnnntttt ((((****lllloooowwwwppppcccc))))(((()))),,,, iiiinnnntttt ((((****hhhhiiiigggghhhhppppcccc))))(((())))))));;;;
  15.  
  16.      vvvvooooiiiidddd mmmmoooonnnnccccoooonnnnttttrrrroooollll((((iiiinnnntttt mmmmooooddddeeee))));;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      NNNNOOOOTTTTEEEE:::: These functions have been moved from the standard C library to the
  20.      _l_i_b_p_r_o_f library.  If a program needs to access these routines it must
  21.      either use the -_p option on the compiler/linker or explicitly link with
  22.      the ----llllpppprrrrooooffff linker option. These functions have been changed to work
  23.      correctly with dynamic shared objects (dsos).
  24.  
  25.      Use of the option -_p during compilation and linking automatically
  26.      generates calls to the _m_o_n_i_t_o_r and _m_o_n_c_o_n_t_r_o_l functions. You need to call
  27.      these functions explicitly only if you want finer control over profiling.
  28.  
  29.      There are three varieties of profiling available:  program-counter (pc)
  30.      sampling, invocation counting, and basic block counting.  The functions
  31.      described on this page provide only pc-sampling, the _p_i_x_i_e(1) command
  32.      must be used to get the other types of profiling information.
  33.  
  34.      The -_p option used during linking forces the link editor (_l_d) to include
  35.      a special start-up routine _m_c_r_t_1._o and the library _l_i_b_p_r_o_f._a that
  36.      contains these routines.
  37.  
  38.      monitor(mode, grain, lowpc, highpc) is used to initialize pc-sampling.
  39.      _g_r_a_i_n is the number of instruction counted in one bucket. _l_o_w_p_c and
  40.      _h_i_g_h_p_c are currently unused. For finer control, the user can use the
  41.      _m_o_n_c_o_n_t_r_o_l() function.
  42.  
  43.      monitor(PCS_MAIN, grain, 0, 0) specifies that only the MAIN module of a
  44.      shared program is included for program counter sampling.
  45.      monitor(PCS_WHOLE, grain, 0, 0) specifies that the whole program
  46.      (including dynamic shared libraries) is included for program counter
  47.      sampling.  monitor(PCS_MAIN, grain, 0, 0) and monitor(PCS_WHOLE, grain,
  48.      0, 0) are equivalent for non-shared programs.
  49.  
  50.      Without mcrt1.o , to profile the entire program, use:
  51.  
  52.           monitor (PCS_WHOLE, 2, 0, 0);
  53.  
  54.      To stop execution monitoring and write the results in an output file,
  55.      use:
  56.  
  57.           moncontrol (PCS_DONE);
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))                                                        MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))
  71.  
  72.  
  73.  
  74.      _m_o_n_c_o_n_t_r_o_l selectively disables and re-enables pc-sampling within a
  75.      program.  To disable pc-sampling, use:
  76.  
  77.           moncontrol (PCS_SUSPEND);
  78.  
  79.      to resume, use:
  80.  
  81.           moncontrol (PCS_RESUME);
  82.  
  83.      This is done automatically by a special _e_x_i_t function linked in with
  84.      _m_c_r_t_1._o.
  85.  
  86.      This allows the cost of particular operations to be measured.  If any
  87.      profiling is enabled, moncontrol cannot prevent the program from
  88.      generating a file of profiling information on exit.
  89.  
  90.      The location of the profiling output files, and whether or not calls to
  91.      monitor will cause pc-sampling to be started are determined by the
  92.      environment variable  PROFDIR.  If PROFDIR is not set, the results will
  93.      be placed in a file called mon.out in the current directory (unless, as
  94.      explained below, shared address processes are being pc- sampled).  If
  95.      PROFDIR is set to a nonempty string, it constructs a file name of the
  96.      form _p_r_o_f_d_i_r/_p_r_o_g_n_a_m_e._m_o_n._p_i_d , where "profdir" comes from the
  97.      environment variable, "pid" is the process id, and "progname" is the
  98.      "argv[0]" for the process.
  99.  
  100.      It is also possible via _m_o_n_c_o_n_t_r_o_l to profile parts of a program, write
  101.      those results to a file, and continue profiling.  The
  102.  
  103.           moncontrol (PCS_NEWPHASE);
  104.  
  105.      function causes the current contents of the profiling buffer to be
  106.      written to a file of the form "profdir/progname.mon.pid.phase_id" or
  107.      "mon.out.phase_id"; "phase_id" is the string "p<n>", where <n> starts
  108.      from 1 and increments for each call to moncontrol(PCS_NEWPHASE).  The
  109.      profiling buffer is cleared after every call to moncontrol.
  110.  
  111.      If a program that is performing pc-sampling executes the _f_o_r_k(2) system
  112.      call, the profiling information is duplicated, and each will continue to
  113.      pc-sample into their own buffer.  However, it is important that PPPPRRRROOOOFFFFDDDDIIIIRRRR
  114.      be defined otherwise the last process to exit will overwrite the values
  115.      in _m_o_n._o_u_t of the rest.
  116.  
  117.      If a program that is performing pc-sampling executes the _s_p_r_o_c(2) system
  118.      call, _m_c_r_t_1._o initiates profiling for the new process.  At exit time,
  119.      regardless of whether PPPPRRRROOOOFFFFDDDDIIIIRRRR is set, unique file names will be created.
  120.  
  121. FFFFIIIILLLLEEEESSSS
  122.      mon.out             default name for output file
  123.      libprof.a           routines for pc-sampling
  124.      /usr/lib/mcrt1.o    special start-up routine for pc-sampling
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))                                                        MMMMOOOONNNNIIIITTTTOOOORRRR((((3333XXXX))))
  137.  
  138.  
  139.  
  140. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  141.      cc(1), pixie(1), prof(1), ld(1), fork(2), profil(2), sprofil(2) and
  142.      sproc(2).
  143.  
  144. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  145.      _m_o_n_i_t_o_r returns 0 on failure due to insufficient memory.  It returns 1
  146.      for a successful call.  If the result file cannot be created or written
  147.      to, an error message is printed on stderr and a 0 is returned.  _m_o_n_i_t_o_r
  148.      forces the caller to exit on a failed call to _m_o_n_i_t_o_r.
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.